System Architecture - DevolutionSync

Overview

DevolutionSync is built on a modern PHP stack using the Model-View-Controller (MVC) architectural pattern. The system provides a robust, scalable foundation for enterprise product return and deviation management.

Technology Stack

PHP 8.2

Server-side application logic

Apache 2.4

Web server with mod_rewrite

MySQL 8.0

Relational database storage

Core Technologies

Runtime: PHP 8.2 with Apache 2.4
Database: MySQL 8.0 with PDO driver
Extensions: pdo, pdo_mysql, mysqli
Architecture: MVC pattern with front controller
Session Management: Native PHP sessions with security features

Application Architecture

High-Level Architecture

The system follows a layered architecture with clear separation of concerns:

┌─────────────────────────────────────┐
│         Client Browser              │
└──────────────┬──────────────────────┘
               │ HTTP Request
               ▼
┌─────────────────────────────────────┐
│      Apache Web Server (Port 80)    │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      index.php (Front Controller)   │
│  • URL Routing                      │
│  • Session Initialization           │
│  • Controller Dispatch              │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│         Controllers Layer           │
│  • AuthController                   │
│  • AdminController                  │
│  • PanelController                  │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│           Models Layer              │
│  • DevolucionModel                  │
│  • ProductoModel                    │
│  • ConsultaModel                    │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Conexion (PDO Database)        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│          MySQL Database             │
│  • devoluciones                     │
│  • usuarios                         │
│  • notificaciones                   │
└─────────────────────────────────────┘

Request Flow

Front Controller Pattern

All HTTP requests are routed through index.php, which acts as the front controller:

index.php

<?php
// 1. Load configuration
require_once 'Config/Conexion.php';

// 2. Start session
if (session_status() === PHP_SESSION_NONE) session_start();

// 3. Determine requested URL
$url = isset($_GET['url']) ? $_GET['url'] : '';

if (empty($url)) {
    if (isset($_SESSION['logged_in']) && $_SESSION['logged_in'] === true) {
        // Redirect to dashboard if logged in
    }
}

// 4. Parse URL and route request
$urlParts = explode('/', rtrim($url, '/'));
$controllerName = ucfirst($urlParts[0]) . 'Controller';
$method = isset($urlParts[1]) ? $urlParts[1] : 'index';

// 5. Execute controller method
$controllerPath = 'Controllers/' . $controllerName . '.php';

if (file_exists($controllerPath)) {
    require_once $controllerPath;
    if (class_exists($controllerName)) {
        $controller = new $controllerName();
        if (method_exists($controller, $method)) {
            $controller->{$method}();
        } else {
            die("Error: Method '$method' does not exist.");
        }
    }
} else {
    die("Error: Controller '$controllerName' not found.");
}

URL Routing Examples

GET /index.php?url=auth/login
├─> Controller: AuthController
├─> Method: login()
└─> View: Views/auth/login.php

The routing system uses .htaccess with mod_rewrite to clean URLs and route all requests through index.php.

Session Management

Authentication Flow

DevolutionSync implements role-based access control (RBAC) with three user levels:

AuthController.php (excerpt)

private function getRedirectUrl($grado) {
    switch ($grado) {
        case 1: 
            // Administrator - Full access
            return 'index.php?url=home/index'; 
        case 2: 
            // Auxiliary - Create deviations
            return 'index.php?url=devolucion/crear'; 
        case 3: 
            // Consultant - Read-only access
            return 'index.php?url=consulta/index';
        default: 
            return 'index.php?url=auth/index';
    }
}

Session Security Features

Session Initialization

if (session_status() === PHP_SESSION_NONE) session_start();
$_SESSION['user'] = $user['USR'];
$_SESSION['nombre'] = $user['NOMBRE'];
$_SESSION['grado'] = $user['GRADO'];
$_SESSION['logged_in'] = true;
$_SESSION['last_activity'] = time();

session_regenerate_id(true); // Prevent session fixation

Access Control Middleware

AdminController.php (excerpt)

public function __construct() {
    if (session_status() === PHP_SESSION_NONE) session_start();
    
    // Verify authentication and permissions (Only Grade 1 - Administrator)
    if (!isset($_SESSION['logged_in']) || $_SESSION['grado'] != 1) {
        header('Location: index.php?url=auth/index');
        exit;
    }
    
    $this->model = new DevolucionModel();
    $this->consultaModel = new ConsultaModel();
}

All controllers check session status in their constructors to enforce authentication and authorization before executing any business logic.

Database Connection

PDO Connection Management

The Conexion class provides a centralized database connection using PDO:

config/conexion.php

<?php
class Conexion {
    public static function Conectar() {
        // Database credentials
        $host = '192.200.100.40';
        $db   = 'devolutionsync';
        $user = 'SANMARINO';
        $pass = 'sanmarino2021*';
        $charset = 'utf8';

        // Connection string
        $dsn = "mysql:host=$host;dbname=$db;charset=$charset";

        $opciones = [
            PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::ATTR_EMULATE_PREPARES   => false,
        ];

        try {
            $pdo = new PDO($dsn, $user, $pass, $opciones);
            return $pdo;
        } catch (PDOException $e) {
            die("Connection error (PDO): " . $e->getMessage());
        }
    }
}

Connection Features

Error Handling: Exceptions for all database errors
Fetch Mode: Associative arrays by default
Prepared Statements: Real prepared statements (not emulated)
UTF-8 Support: Full Unicode character support
Singleton Pattern: Static method ensures consistent connections

File Upload Handling

Evidence Upload System

DevolutionSync handles file uploads for deviation evidence:

File Validation

Validates file type, size, and format before processing

Secure Storage

Stores files in /uploads directory with sanitized names

Database Reference

Saves file path in devoluciones.evidencia column

Access Control

Files accessible only to authenticated users

DevolucionModel.php (excerpt)

public function guardar($datos) {
    $sql = "INSERT INTO devoluciones (
                nit, nombre_cliente, direccion, item_producto, descripcion_producto, 
                unidad, kg, motivo, cantidad_und, cantidad_kg, 
                observacion, usuario_creador, estado, fecha_creacion, evidencia
            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'Pendiente', NOW(), ?)";
    
    $stmt = $this->db->prepare($sql);
    
    return $stmt->execute([
        // ... other parameters ...
        $datos['evidencia'] ?? null // Handle null if no evidence
    ]);
}

Security Architecture

Authentication & Authorization

Authentication

Password verification
Session regeneration
Login attempt tracking
Secure logout

Authorization

Role-based access (GRADO)
Controller-level checks
Method-level validation
Resource ownership

Data Security

Prepared Statements: All SQL queries use PDO prepared statements
Input Validation: Server-side validation in controllers
XSS Prevention: Output escaping in views
CSRF Protection: Session-based token validation
SQL Injection: Prevented through parameterized queries

Performance Considerations

Optimization Strategies

Database Indexing: Primary keys and foreign keys on all tables
Query Optimization: Efficient JOIN operations and WHERE clauses
Connection Pooling: PDO persistent connections available
Session Management: File-based sessions (can be moved to Redis)
Caching: Opcache enabled in PHP 8.2

Scalability

The architecture supports horizontal scaling by:

Separating database server from application server
Using Docker containers for easy replication
Implementing stateless session management (future: Redis)
Database replication for read-heavy operations

Error Handling

Exception Management

AdminController.php (excerpt)

public function revisar() {
    if ($_SERVER['REQUEST_METHOD'] === 'POST') {
        try {
            // Validate received data
            $id = intval($_POST['id_devolucion'] ?? 0);
            $accion = trim($_POST['accion'] ?? '');
            
            if ($id <= 0) {
                throw new Exception('Invalid deviation ID');
            }
            
            if (!in_array($accion, ['aprobado', 'rechazado'])) {
                throw new Exception('Invalid action');
            }
            
            // Process review
            $resultado = $this->model->procesarRevision($id, $accion, $codigo, $obs, $revisor);
            
            if ($resultado) {
                header('Location: index.php?url=admin/index&msg=success');
            } else {
                throw new Exception('Database error processing review');
            }
            
        } catch (Exception $e) {
            error_log("Error in AdminController::revisar - " . $e->getMessage());
            header('Location: index.php?url=admin/index&msg=error');
        }
        exit;
    }
}

Logging Strategy

Error Logs: PHP error_log() for application errors
Database Logs: Transaction rollback on failures
User Feedback: Friendly error messages via URL parameters
Debug Mode: Detailed errors in development environment

Next Steps

Database Schema

Explore complete database structure and relationships

MVC Structure

Learn about Controllers, Models, and Views

Docker Deployment

Deploy DevolutionSync with Docker

API Reference

View complete API documentation

​Overview

​Technology Stack

PHP 8.2

Apache 2.4

MySQL 8.0

​Core Technologies

​Application Architecture

​High-Level Architecture

​Request Flow

​Front Controller Pattern

​URL Routing Examples

​Session Management

​Authentication Flow

​Session Security Features

​Database Connection

​PDO Connection Management

​Connection Features

​File Upload Handling

​Evidence Upload System

​Security Architecture

​Authentication & Authorization

Authentication

Authorization

​Data Security

​Performance Considerations

​Optimization Strategies

​Scalability

​Error Handling

​Exception Management

​Logging Strategy

​Next Steps

Database Schema

MVC Structure

Docker Deployment

API Reference

Overview

Technology Stack

Core Technologies

Application Architecture

High-Level Architecture

Request Flow

Front Controller Pattern

URL Routing Examples

Session Management

Authentication Flow

Session Security Features

Database Connection

PDO Connection Management

Connection Features

File Upload Handling

Evidence Upload System

Security Architecture

Authentication & Authorization

Data Security

Performance Considerations

Optimization Strategies

Scalability

Error Handling

Exception Management

Logging Strategy

Next Steps